<?php 
/**
 * IDbSchema interface.
 * 获取表的信息, 包含表的主键和外键, 列的情况.
 * @author Huan Song <iphper@yeah.net>
 * @version $Id: interfaces.php 1 2011-06-06 11:12:15Z huan.song $
 * @package system.base
 * @since 2.0
 */
interface IDbSchema
{
	/**
	 * 收集表的信息.
	 * @param string 表名.
	 * @return IDbSchema $table. 如果表不存在, 返回null.
	 */
	public function loadTable($name);
	
	/**
	 * 引用一个表名, 被引用的表名可以放在SQL语句中执行.
	 * @param string $name 表名.
	 * @return string 被引用的表名.
	 */
	public function quoteTableName($name);
	
	/**
	 * 引用一个列名, 被引用的列名可以放在SQL语句中执行.
	 * @param string $name 列名.
	 * @return string 被引用的列名.
	 */
	public function quoteColumnName($name);
	
	/**
	 * 引用多个个列名, 被引用的列名可以放在SQL语句中执行.
	 * @param string $name 列名.
	 * @return string 被引用的列名.
	 */
	public function quoteColumnNames(array $names);
}

/**
 * IDbTableSchema interface.
 * 保存表的信息, 包含表的主键和外键, 列的情况.
 * @author Huan Song <iphper@yeah.net>
 * @version $Id: interfaces.php 1 2011-06-08 13:56:06Z huan.song $
 * @package system.base
 * @since 2.0
 */
interface IDbTableSchema
{
	/**
	 * 获取指定列的信息.
	 * @param string $name 列名.
	 * @return IDbColumnSchema|null 列信息.
	 */
	public function getColumn($name);
	
	/**
	 * @return array 所有的列名.
	 */
	public function getColumnNames();
}

/**
 * IDbColumnSchema interface.
 * 保存列的信息.
 * @author Huan Song <iphper@yeah.net>
 * @version $Id: interfaces.php 1 2011-06-08 22:17:17Z huan.song $
 * @package system.base
 * @since 2.0
 */
interface IDbColumnSchema
{
	/**
	 * 通过列的类型, 转换值的类型.
	 * @param mixed $value input value
	 * @return mixed converted value
	 */
	public function typecast($value);
}

/**
 * IView interface.
 * 模板解析接口, 所有模板解析类都要实现此接口.
 * @author Huan Song <iphper@yeah.net>
 * @version $Id: interfaces.php 1 2010-08-17 13:40:06Z huan.song $
 * @package system.base
 * @since 2.0
 */
interface IView
{
	/**
     * 获取模板引擎.
     * @return Object View.
     */
    public function getEngine();
	
    /**
     * 通过键$key从$_tpl_vars中获取值.
     * <pre>
     * $view = new CView();
     * $username = $view->username;
     * $email = $view->email;
	 * </pre>
     * @param string $key.
     * @return string|array|...
     * @see __set
     */
    public function __get($key);
	
    /**
     * 判读$_tpl_vars中键$key是否存在.
     * <pre>
     * $view = new CView();
     * $bool = isset($view->username);
     * $bool = isset($view->email);
	 * </pre>
     * @param string $key.
     * @return boolean.
     */
    public function __isset($key);

    /**
     * 向$_tpl_vars中设置键值对.
     * <pre>
     * $view = new CView();
     * $view->username = 'iphper';
     * $view->email = 'iphper@yeah.net';
	 * </pre>
     * @param string $key 变量名.
     * @param mixed $value 变量值.
     * @return void.
     * @see assign().
     */
    public function __set($key, $value);

    /**
     * 删除$_tpl_vars中键为$key的一组键值对.
     * <pre>
     * $view = new CView();
     * unset($view->username);
     * unset($view->email);
	 * </pre>
     * @param string $key.
     * @return void.
     */
    public function __unset($key);

    /**
     * 向$_tpl_vars中设置键值对.
     * <pre>
     * $view = new CView();
	 * $view->assign('username', 'iphper');
	 * $view->assign('email', 'iphper@yeah.net');
	 * 
	 * $vars = array('username' => 'iphper', 'email' => 'iphper@yeah.net');
	 * $view->assign($vars);
	 * </pre>
     * @param array|string $tpl_var 变量名. 如果为数组, 则循环数组赋给$_tpl_vars.
     * @param array|string|null|.etc $value 变量值.
     * @see __set().
     */
    public function assign($tpl_var, $value = null);
	
    /**
     * 获取$_tpl_vars中所有键值对.
     * <pre>
     * $view = new CView();
	 * $vars = $view->getVars();
	 * </pre>
     * @return array $_tpl_vars中所有键值对.
     */
    public function getVars();
	
    /**
     * 清空$_tpl_vars中所有键值对.
     * <pre>
     * $view = new CView();
	 * $view->clearVars();
	 * </pre>
     * @return void.
     */
    public function clearVars();
    
    /**
     * 解析模板.
     * <pre>
     * $view = new CView();
	 * $html = $view->fetch('users/login.html', false);
	 * 
	 * $view->fetch('users/login.html', true); 直接输出结果.
	 * </pre>
     * @param string $tpl 模板名.
     * @param boolean $display 是否输出模板内容到浏览器.
     * @return string 解析后模板内容.
     * @throws CViewException. 如果模板文件不存在, 抛出异常.
     * @see display
     */
    public function fetch($tpl, $display = false);
    
    /**
     * 解析并输出模板内容到浏览器.
     * <pre>
     * $view = new CView();
	 * $view->display('users/login.html');
	 * </pre>
     * @param $tpl 模板名.
     * @return void.
     * @see fetch
     */
    public function display($tpl);
}
